It doesn't feel right to require users to make a cast for type safety - perhaps a utility function would provide better DX?

Great idea. I will implement it later

Okay, I added a utility function to avoid the type cast. Let me know if you had something different in mind

It would be great if the user could reference the various generated OpenAPI schemas here. Will a simple $ref work here? Can you add a test that verifies that please?

I'm not sure if I understand you correctly. The generated OpenAPI schemas aren't yet available here, as this definition will be used to generate them.

If you know the correct component name, you can write a ref inside your custom endpoint definition - $ref: "#/components/schemas/UserResponse" or something like that. My question is if this will work as expected

Thanks for the clarification 👍 That should be possible. I'll add a test for it

For what is worth I tested this branch on my project, and in order for this to work (using $ref to existing definitions), I needed to change this in generateCollectionCustomEndpointResponses:

const generateCollectionCustomEndpointResponses = (
  collection: Collection,
): Record<string, OpenAPIV3_1.ResponseObject & OpenAPIV3.ResponseObject> => {
      ...
      for (const [statusCode, resp] of Object.entries(documentation.responses || {})) {
        ...
        responses[key] = {
          description: `Custom endpoint response for ${singular} with method ${endpoint.method} and status code ${statusCode}`,
          content: {
            'application/json': {
              schema: resp.$ref
                ? composeRef('schemas', resp.$ref) // added this
                : composeRef('schemas', singular, {
                    suffix: `CustomEndpoint${upperFirst(endpoint.method)}${statusCode}`,
                  }),
            },
          },
        }
      }
    }
  }

  return responses
}

Otherwise, I could not get a ref working at all.

Now, I may be doing something dumb; I don't really know well how this package (or this PR) works.

With that change, I could reference the User object by doing this in the custom openapi section:

 responses: {
            200: {
              "$ref": "User"
            },
          },

UserResponse does not work.

I'm a bit lost here. Does this still support both 3.0 and 3.1? Maybe we should enforce 3.1 syntax and convert it if the plugin is configured for 3.0?

This is just a type generic for the user to specify what OpenAPI version he's using. If he omits this, 3.1 is used (for the types), but he has the possibility to specify 3.0 as well. The same way he needs to specify the version in the plugin config. Although I just noticed that 3.0 is the default there.

So yes, it still supports both 3.0 and 3.1. I would change it to default to 3.0, so that it's in sync with the default config version.